package com.icongyou.enterprise.talent_analysis.service;

import com.icongyou.enterprise.talent_analysis.entity.PortraitResponse;
import com.icongyou.enterprise.talent_analysis.entity.dto.StudentFeatureContext;
import com.icongyou.enterprise.talent_analysis.entity.template.TemplateDimension;

import java.util.List;

/**
 * AI辅助的人才画像评估服务
 * 负责在自定义维度下生成量化评分标准并执行评分
 */
public interface AIPortraitEvaluationService {

    /**
     * 基于自定义模板和AI分析,为学生生成画像评分
     * 
     * @param studentId 学生ID
     * @param templateId 画像模板ID
     * @return 画像评分结果
     */
    PortraitResponse computeCustomPortrait(String studentId, String templateId);

    /**
     * AI分析学生特征上下文,提取关键信息用于评分
     * 
     * @param studentId 学生ID
     * @return 学生特征上下文
     */
    StudentFeatureContext extractStudentFeatures(String studentId);

    /**
     * 使用AI为自定义维度生成量化评分标准
     * 
     * @param dimensions 自定义维度列表
     * @param sampleFeatures 样本学生特征(用于校准)
     * @return 增强后的维度(包含AI生成的评分规则)
     */
    List<TemplateDimension> generateScoringStandards(
        List<TemplateDimension> dimensions, 
        List<StudentFeatureContext> sampleFeatures
    );

    /**
     * 使用AI理解维度语义并推荐数据映射
     * 
     * @param dimensionName 维度名称
     * @param dimensionDescription 维度描述
     * @return AI推荐的数据源字段列表
     */
    List<String> recommendDataMapping(String dimensionName, String dimensionDescription);
    
    /**
     * 从教师评语中提取关键词（用于词云图展示）
     * 
     * @param studentId 学生ID
     * @return 关键词及其出现频次的Map
     */
    java.util.Map<String, Integer> extractTeacherCommentKeywords(String studentId);
}
